# parseCSV Cheat Sheet #

_These notes based on parseCSV v0.4.3 beta_


## Basic usage

	$csv = new parseCSV('file.txt');
	$csv = new parseCSV('string that isn't a file on disk.');

	foreach ($csv->heading as $cell) {
		...
	}

	foreach ($csv->data as $row) {
		foreach ($row as $cell) {
			...
		}
	}


For fine grained control declare the object, then set the strings in the con
`parsecsv.lib.php`'s "Configuration" section.
	
	$csv = new parseCSV();
	$csv->delimiter = "\t";
	$csv->parse('data.tsv');


## Advanced Usage

	To auto-determine enclosing and separating characters:
	
	$csv->auto('data.csv'); 

	var $sort_reverse = false;



## Data Variables 

	$csv->data			// 2D array (seconds array is keyed by the
						//   column name: $csv->data[1]['Date'] ).
	$csv->titles		// 1D array 
	$csv->$error_info 	// 1D array

	$csv->$file;		// Current file (I think mainly for ouput?)
	$csv->$file_data;	// CSV string.

	$csv->$error;		// 0=OK, 1 OR 2 == Error. 
	$csv->error_info; 	// array: detailed error info


# Configuration Options

(The values bellow are the defaults)

Input/General:

	$csv->encoding('ISO-8859-1', 'ISO-8859-1');		// Manually set input/output encoding.

	$csv->delimiter = ',';
	$csv->enclosure = '"';

	$csv->heading = false;			// First line isn't heading
	$csv->field = array();			// Manually set column names.

	$csv->conditions = null;		// SQL style conditions, ie 'author does not contain dan brown'

	$csv->sort_by = 'id';			// sort rows using the id column.
	$csv->$sort_reverse = false;

Output:

	$csv->output_delimiter = ',';
	$csv->output_filename = "file.csv";

	$csv->linefeed = "\r\n";	// Used for file output.

	$string = output (false, null, $data, $headers);
			// the first two options allow you to "print to browser".


## Functions

Paramater Notes:

 -	You can ignore most options -- they'll use defaults.  

 -	`$input`: file/string  
	`$file`: filename  
	You can leave these off by calling `$csv->file = ...` first.

 -	`$offset`, `$limit`  
	These select rows from the data.
 
 -	`$fields`: field names (ie titles)  

 -	`$append`: used by save to add data to the end of a file.
 
 -	`$is_php`: I'm not really sure what this means; "if a php die() call
	should be put on the first line of the file, this is later ignored when
	read."


Constructor:

	/* no_return */		parseCSV ($input = null, $offset = null, $limit = null, $conditions = null);

Main Functions:

	/* no_return */		parse ($input = null, $offset = null, $limit = null, $conditions = null);
	$true_false = 		save ($file = null, $data = array(), $append = false, $fields = array());
	$string = 			output ($output = true, $filename = null, $data = array(), $fields = array(), $delimiter = null);
	/* no_return */		encoding ($input = null, $output = null);
	$delimiter =		auto ($file = null, $parse = true, $search_depth = null, $preferred = null, $enclosure = null);


Core Functions:

	$array_2d_or_false =	parse_file ($file = null);
	$array_2d_or_false =	parse_string ($data = null);
	csv_string = 			unparse ( $data = array(), $fields = array(), $append = false , $is_php = false, $delimiter = null) ;
	$true_false = 			load_data ($input = null);


## Notes and Gotchas

_Some all of these may have been fixed in later versions._

- **Newlines at the start of a row**.  The newlines at the end of a line get
  appended to the beginning of the next line. Thus $header[0] doesn't have a
  `\n` preppended, but $data[0][0] does.  

  I couldn't find a way to stop this (including setting $parser->linefeed), and
  used regex to fix this in the end.

- **Titles**.  If you don't set `$heading = false` your first line will be in
  `$titles`, not `$data`.

- **Remember the newlines**.  Lines must end with a newline before parseCSV will
  parse them as an array row -- it's easy to have the last line disapear from
  the ouput.

- **parse\_string()**.  `parse_string()` won't fill out `$data` but it will fill
  out `$titles`. What would have gone into `$data` is returned fromt the
  function, ie `$arr = $csv->parse_string($str)`


- **UNIX newlines**.  I found that I didn't need to set `$linefeed = "\n"` it parse UNIX strings
  when set to the Windows `\r\n` default.

- **Space around the comma and zeros**.  Space around commas (Excel style) are
  removed. Leading zeros aren't touched.

		$string = "this, has space , and zeros, 0022\n";
		// 
		// is brocken up into this,
		//    <this> <has space> <and zeros> <0022>


